super-ux 0.19.0 → 0.26.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +400 -0
- package/README.md +185 -140
- package/bin/super-ux.js +15 -3
- package/cursor/rules/super-ux.mdc +12 -6
- package/cursor/rules/ux-audit.mdc +9 -2
- package/cursor/rules/ux-flows.mdc +20 -3
- package/cursor/rules/ux-foundation.mdc +9 -0
- package/cursor/rules/ux-scenarios.mdc +10 -3
- package/package.json +6 -2
- package/plugins/super-ux/scripts/ux_lint.py +231 -0
- package/templates/README.md +4 -2
- package/templates/claude-rule.md +9 -4
- package/templates/flows.md +2 -0
- package/templates/foundation.md +12 -2
- package/templates/screens.md +5 -0
package/README.md
CHANGED
|
@@ -4,74 +4,52 @@
|
|
|
4
4
|
[](https://github.com/ssheleg/super-ux/actions/workflows/validate.yml)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
|
-
Scenario-driven UI development for AI agents
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
the
|
|
7
|
+
**Scenario-driven UI development for AI agents** — Claude Code, Cursor, and
|
|
8
|
+
70+ other agents.
|
|
9
|
+
|
|
10
|
+
Coding agents build bad interfaces for one reason: they write UI without a
|
|
11
|
+
model of user behavior. Screens appear feature by feature; error states,
|
|
12
|
+
empty states, and cross-feature flows get invented ad hoc or skipped, and
|
|
13
|
+
three prompts later the agent quietly rewrites something you already
|
|
14
|
+
approved. super-ux fixes the process, not the symptom: a versioned design
|
|
15
|
+
chain in `docs/ux/` becomes the source of truth, written and approved
|
|
16
|
+
*before* UI exists, updated in the same change as any behavior change, and
|
|
17
|
+
used as the checklist for evidence-backed audits of the code.
|
|
17
18
|
|
|
18
19
|
```mermaid
|
|
19
20
|
flowchart LR
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
G --> H[Prioritized fix plan\nFreq × Severity × Solvability] --> D
|
|
21
|
+
F["Foundation<br/>personas · JTBD<br/>journeys · stories"] --> L["Flows<br/>task analysis<br/>+ branches"]
|
|
22
|
+
L --> S["Screens<br/>states · elements<br/>Figma frames"]
|
|
23
|
+
S --> C["Scenarios<br/>action → response<br/>alt + error paths"]
|
|
24
|
+
C --> B["Build UI<br/>only now"]
|
|
25
|
+
B --> A["Audit<br/>code vs the chain<br/>file:line evidence"]
|
|
26
|
+
A --> P["Fix plan<br/>Freq × Severity<br/>× Solvability"]
|
|
27
|
+
P --> B
|
|
28
|
+
B -.->|same change| C
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
per-product completeness checklists, the `draft → validated → implemented`
|
|
54
|
-
lifecycle, audit verdicts and severities.
|
|
55
|
-
|
|
56
|
-
## The hard rule
|
|
57
|
-
|
|
58
|
-
- `docs/ux/scenarios.md` is the source of truth for all user-facing
|
|
59
|
-
behavior; foundation (WHY) and flows (HOW) are the layers it traces to.
|
|
60
|
-
- Any change touching user-facing behavior or interface updates **in the
|
|
61
|
-
same change**: scenarios, affected flows, the affected screens in
|
|
62
|
-
`docs/ux/screens.md` (the UI map — states, elements, coverage), and (Figma
|
|
63
|
-
on) the Figma frames plus their links. Code that diverges from a screen's
|
|
64
|
-
record, or a stale Figma link, is drift the audit flags.
|
|
65
|
-
- Any new feature or project **starts** with the chain: which job, which
|
|
66
|
-
journey stage, which story — then flows and scenarios, validated and
|
|
67
|
-
approved.
|
|
68
|
-
- **Do not write interface code until the UX workflow is done first** — the
|
|
69
|
-
foundation → flows → scenarios chain designed and approved, and (when
|
|
70
|
-
Figma is enabled, the default) the UI mocked up in Figma with every screen
|
|
71
|
-
linked to its frame. Building UI before this is the mistake super-ux
|
|
72
|
-
exists to prevent.
|
|
73
|
-
|
|
74
|
-
## Install
|
|
31
|
+
Every layer traces to the one above it. New product? Build it forward. Existing
|
|
32
|
+
codebase? The same artifacts get filled in backwards from the code, tagged
|
|
33
|
+
`inferred` until you confirm them — the gap between "is" and "should" becomes
|
|
34
|
+
your improvement backlog.
|
|
35
|
+
|
|
36
|
+
## What you get
|
|
37
|
+
|
|
38
|
+
- **Context stops evaporating.** You describe who the product is for and what
|
|
39
|
+
job it does once; every later prompt inherits that instead of re-deriving it
|
|
40
|
+
from the diff.
|
|
41
|
+
- **Scenarios become acceptance criteria.** "Make it nicer" can no longer mean
|
|
42
|
+
"silently change the error handling" — a file says what the error handling
|
|
43
|
+
does, and the audit checks the code against it.
|
|
44
|
+
- **Drift gets caught, deterministically.** A linter fails on missing Figma
|
|
45
|
+
frames, broken traces, orphan screens, and index desync; audits report what
|
|
46
|
+
no longer matches with `file:line` evidence. That is the review pass you'd
|
|
47
|
+
otherwise never run.
|
|
48
|
+
- **Designer artifacts without being a designer.** Personas, jobs to be done,
|
|
49
|
+
journeys, flows, screen states, wireframes, Figma frames — produced in your
|
|
50
|
+
repo, in the vocabulary a design review actually uses.
|
|
51
|
+
|
|
52
|
+
## Quick start
|
|
75
53
|
|
|
76
54
|
### Claude Code
|
|
77
55
|
|
|
@@ -80,51 +58,144 @@ lifecycle, audit verdicts and severities.
|
|
|
80
58
|
/plugin install super-ux@super-ux
|
|
81
59
|
```
|
|
82
60
|
|
|
83
|
-
Then in your project
|
|
84
|
-
`docs/ux/`, builds the
|
|
85
|
-
|
|
61
|
+
Then in your project, run `/ux` and answer in plain words. First run installs
|
|
62
|
+
the hard rule, seeds `docs/ux/`, and builds the chain; every later run reports
|
|
63
|
+
status and recommends one next action. You never pick a skill or a layer —
|
|
64
|
+
routing is the agent's job.
|
|
86
65
|
|
|
87
|
-
###
|
|
66
|
+
### Cursor
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npx super-ux --cursor /path/to/your/project
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Copies the rules into `.cursor/rules/` (one always-on hard rule + four
|
|
73
|
+
agent-requested rules), seeds `docs/ux/`, and installs the linter. An existing
|
|
74
|
+
scenario base is never overwritten; re-run with `--force` after a release to
|
|
75
|
+
refresh rules and linter only.
|
|
76
|
+
|
|
77
|
+
### Any agent (70+, via the skills CLI)
|
|
88
78
|
|
|
89
79
|
```sh
|
|
90
|
-
npx skills add ssheleg/super-ux #
|
|
80
|
+
npx skills add ssheleg/super-ux # all four skills, current project
|
|
91
81
|
npx skills add ssheleg/super-ux -g # user-global
|
|
92
82
|
npx skills add ssheleg/super-ux --skill ux-audit # one skill
|
|
93
83
|
```
|
|
94
84
|
|
|
95
85
|
[vercel-labs/skills](https://github.com/vercel-labs/skills) discovers the
|
|
96
86
|
skills through this repo's marketplace manifest and installs them for Claude
|
|
97
|
-
Code, Cursor, Codex, OpenCode and others.
|
|
98
|
-
|
|
99
|
-
|
|
87
|
+
Code, Cursor, Codex, OpenCode and others. This channel ships the skills only —
|
|
88
|
+
the `/ux` commands come with the plugin, the always-on hard rule with the
|
|
89
|
+
Cursor install.
|
|
100
90
|
|
|
101
|
-
### Interactive (pick
|
|
91
|
+
### Interactive (pick channels and agents)
|
|
102
92
|
|
|
103
93
|
```sh
|
|
104
94
|
npx super-ux
|
|
105
95
|
```
|
|
106
96
|
|
|
107
|
-
Multi-select menu (space
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
97
|
+
Multi-select menu (space toggles, `a` selects everything, enter installs):
|
|
98
|
+
skills for any of 70+ agents, Cursor rules into a project, and the Claude Code
|
|
99
|
+
plugin user-globally — any combination in one run. Also works straight from
|
|
100
|
+
GitHub: `npx github:ssheleg/super-ux --cursor <dir>`, or clone and run
|
|
101
|
+
`./install.sh --cursor <dir>`.
|
|
111
102
|
|
|
112
|
-
|
|
103
|
+
## The hard rule
|
|
113
104
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
105
|
+
Installed into your project's `CLAUDE.md` (and as the always-on Cursor rule):
|
|
106
|
+
|
|
107
|
+
- `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
|
|
108
|
+
foundation (WHY), flows (HOW), and screens (the UI map) are the layers it
|
|
109
|
+
traces to.
|
|
110
|
+
- Any change touching user-facing behavior or interface updates **in the same
|
|
111
|
+
change**: scenarios, affected flows, the affected screens in
|
|
112
|
+
`docs/ux/screens.md`, and — when Figma is on — the frames plus their links.
|
|
113
|
+
Code that diverges from a screen's record, or a stale Figma link, is drift
|
|
114
|
+
the audit flags.
|
|
115
|
+
- Any new feature or project **starts** with the chain: which job, which
|
|
116
|
+
journey stage, which story — then flows, screens, and scenarios, validated
|
|
117
|
+
against the existing base and approved.
|
|
118
|
+
- **Do not write interface code until that workflow is done** — chain designed
|
|
119
|
+
and approved, and (Figma on, the default) the UI mocked up with every screen
|
|
120
|
+
linked to its frame. Building UI before this is the mistake super-ux exists
|
|
121
|
+
to prevent.
|
|
122
|
+
- One **style pack** is the visual identity for the whole product, recorded in
|
|
123
|
+
`docs/ux/screens.md` → Design system. Inventing a palette, type pairing, or
|
|
124
|
+
motion per screen is drift too.
|
|
125
|
+
- Run `python3 docs/ux/lint.py` after any UX change and in CI — it must pass.
|
|
126
|
+
|
|
127
|
+
## Typical cycle
|
|
128
|
+
|
|
129
|
+
1. **`/ux`** — first run sets everything up: foundation first (greenfield:
|
|
130
|
+
an interview about personas, jobs, journeys; existing code:
|
|
131
|
+
reverse-engineering them), then flows, screens, and scenarios derived from
|
|
132
|
+
the stories with full traceability.
|
|
133
|
+
2. **Work normally.** Every user-facing change updates the chain in the same
|
|
134
|
+
change — the always-on rule catches it, `/ux-update` gives manual control.
|
|
135
|
+
New feature ideas get validated against the chain first: which job, which
|
|
136
|
+
journey stage, which story. An idea serving no job is challenged, not
|
|
137
|
+
silently built.
|
|
138
|
+
3. **`/ux-audit`** — batched verification of code against every scenario plus
|
|
139
|
+
its story's acceptance criteria. `deep` adds heuristic, practice, and chain
|
|
140
|
+
coverage passes; `coverage` audits the chain itself. Reports land in
|
|
141
|
+
`docs/ux/audits/YYYY-MM-DD.md`.
|
|
142
|
+
4. **Fix plan.** Findings become `docs/ux/plans/…`: the target interface per
|
|
143
|
+
screen plus a traced CREATE/MODIFY/DELETE table, prioritized by Frequency ×
|
|
144
|
+
Severity × Solvability — written to be executable without the conversation
|
|
145
|
+
that produced it. Build, then re-audit.
|
|
146
|
+
|
|
147
|
+
## Companions (recommended, never required)
|
|
148
|
+
|
|
149
|
+
super-ux owns structure and behavior, and deliberately stops at two edges.
|
|
150
|
+
Each companion is offered once with its one-time install; the chain works
|
|
151
|
+
fine without either.
|
|
152
|
+
|
|
153
|
+
| When | Companion | What it adds |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| At VISUALIZE / BUILD — a frame or a screen is about to be drawn | **[sheleg-design](https://github.com/ssheleg/sheleg-design-skill)** | The look: one locked style pack (palette, type, texture, motion tokens, bans) with ready token CSS — `workbench` for product UI, dashboards and tools; `instrument-console`; `editorial-luxury`; or a new pack on its contract. Plus the motion methodology for cinematic scroll-driven landings. The pack is recorded in `screens.md`; its tokens become the Figma variables *and* the code tokens. `npx sheleg-design-skill` |
|
|
156
|
+
| After an audit or an Improve pass produced a UX plan | **[task-pipeline](https://github.com/ssheleg/task-pipeline)** | Executes the plan end-to-end through gated stages: spec → plan → subagent build → tests → deploy → docs. `/task-pipeline docs/ux/plans/<file>` |
|
|
157
|
+
|
|
158
|
+
The boundary that keeps them from fighting: BP-079..090 and BP-130..135 are
|
|
159
|
+
craft **floors** (contrast, line length, tap targets, spacing rhythm, a motion
|
|
160
|
+
token scale, reduced motion, the narrow viewport) and always win on safety;
|
|
161
|
+
the style pack owns **identity** and wins on look. Whether a trend is adopted
|
|
162
|
+
at all — its mechanism, its cost, its review date — is BP-145/BP-146. Both decisions land in the
|
|
163
|
+
compliance table. Full protocol:
|
|
164
|
+
[visual-identity.md](plugins/super-ux/skills/references/visual-identity.md).
|
|
165
|
+
|
|
166
|
+
## What's inside
|
|
117
167
|
|
|
118
|
-
|
|
119
|
-
repo, or clone and run `./install.sh --cursor <dir>` — same behavior.) Copies the
|
|
120
|
-
rules into `.cursor/rules/` and seeds `docs/ux/`. An existing scenario base
|
|
121
|
-
is never overwritten; re-run with `--force` to update rules after a new
|
|
122
|
-
release.
|
|
168
|
+
Four skills, one entry point, and a set of contracts they all obey.
|
|
123
169
|
|
|
124
|
-
|
|
170
|
+
| Piece | Purpose |
|
|
171
|
+
|---|---|
|
|
172
|
+
| 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 |
|
|
173
|
+
| 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 |
|
|
174
|
+
| 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 |
|
|
175
|
+
| 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 |
|
|
176
|
+
| `/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 |
|
|
177
|
+
| `/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` |
|
|
178
|
+
| `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 |
|
|
179
|
+
| `cursor/rules/*.mdc` | The same methodology for Cursor: one always-on hard rule + four agent-requested rules |
|
|
180
|
+
| `templates/` | Seeds for `docs/ux/`: foundation, flows, screens, scenario base, the folder README, the audit-report skeleton, and the CLAUDE.md rule snippet |
|
|
181
|
+
|
|
182
|
+
The contracts every skill reads:
|
|
183
|
+
|
|
184
|
+
| Reference | Holds |
|
|
185
|
+
|---|---|
|
|
186
|
+
| [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md) | **The contract (ux-contract v4).** File layout, every field name, stable IDs (`P` `JTBD` `JRN` `ST` `FLW` `SCR` `SCN`), completeness checklists, the `draft → validated → implemented` lifecycle, audit verdicts and severities, the UX-plan format |
|
|
187
|
+
| [system-map.md](plugins/super-ux/skills/references/system-map.md) | The whole system on one page — pipeline, files, skills, companions, and the four sync rules; every skill points here |
|
|
188
|
+
| [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward and backwards), task analysis, flow rules, heuristics PRN-01..16, the improvement procedure, anti-patterns |
|
|
189
|
+
| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 146 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, visual craft, Figma structure |
|
|
190
|
+
| [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) | The deterministic bridge: product profile → mandatory consideration sets → per-artifact checklists → a compliance table where every pulled practice gets a verdict. No silent skips, no cargo cult |
|
|
191
|
+
| [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | Which control for which job (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) and the platform rules — Apple HIG, Material 3, W3C ARIA APG, GOV.UK |
|
|
192
|
+
| [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: one style pack for the whole product, where it's recorded, how it meets Figma and code, and the division of labor with the craft floors |
|
|
193
|
+
| [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 |
|
|
125
194
|
|
|
126
|
-
|
|
127
|
-
|
|
195
|
+
## Keeping installs current
|
|
196
|
+
|
|
197
|
+
Global channels (run after a release, then restart the Claude Code session so
|
|
198
|
+
the plugin reloads):
|
|
128
199
|
|
|
129
200
|
```sh
|
|
130
201
|
claude plugin marketplace update super-ux && \
|
|
@@ -132,67 +203,41 @@ claude plugin update super-ux@super-ux && \
|
|
|
132
203
|
npx --yes skills update ux-audit ux-flows ux-foundation ux-scenarios --global --yes
|
|
133
204
|
```
|
|
134
205
|
|
|
135
|
-
Cursor rules
|
|
136
|
-
global rules
|
|
206
|
+
Cursor rules and the seeded `docs/ux/lint.py` are per-project (Cursor has no
|
|
207
|
+
global rules directory) — refresh each project you use:
|
|
137
208
|
|
|
138
209
|
```sh
|
|
139
210
|
npx super-ux@latest --cursor /path/to/your/project --force
|
|
140
211
|
```
|
|
141
212
|
|
|
142
|
-
`--force`
|
|
143
|
-
|
|
144
|
-
|
|
213
|
+
`--force` replaces the rule files and the linter; your scenario base and the
|
|
214
|
+
rest of `docs/ux/` are never touched. Check the published version with
|
|
215
|
+
`npm view super-ux version`.
|
|
145
216
|
|
|
146
|
-
##
|
|
217
|
+
## Contributing
|
|
147
218
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
219
|
+
Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
220
|
+
for the repo layout, the validator, and the release checklist. Everyone taking
|
|
221
|
+
part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md); to report a
|
|
222
|
+
vulnerability, see [SECURITY.md](SECURITY.md). In short:
|
|
223
|
+
`python3 test/validate.py` must pass (CI runs it on every push and PR), and
|
|
224
|
+
edits to `plugins/super-ux/skills/references/` need
|
|
225
|
+
`python3 test/sync_references.py` to refresh the per-skill copies.
|
|
154
226
|
|
|
155
|
-
##
|
|
227
|
+
## Author
|
|
156
228
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
4. Findings become a concrete UX plan (`docs/ux/plans/…`): target interface
|
|
170
|
-
per screen + traced CREATE/MODIFY/DELETE change table, prioritized by
|
|
171
|
-
Frequency × Severity × Solvability — offered for autonomous execution
|
|
172
|
-
via task-pipeline (or your planning workflow); build; repeat.
|
|
173
|
-
|
|
174
|
-
## Development
|
|
175
|
-
|
|
176
|
-
`python3 test/validate.py` checks repo consistency (manifests, versions,
|
|
177
|
-
front-matter, templates, links); CI runs it on every push and PR. Versioning
|
|
178
|
-
is semver; bump `marketplace.json` + `plugin.json` + `CHANGELOG.md` together
|
|
179
|
-
— the validator enforces the sync.
|
|
180
|
-
|
|
181
|
-
## По-русски (коротко)
|
|
182
|
-
|
|
183
|
-
Проблема: агенты генерируют плохие интерфейсы, потому что строят UI без
|
|
184
|
-
модели поведения пользователя. super-ux строит цепочку: **персоны → JTBD →
|
|
185
|
-
карта пути → user stories → UX-сценарии → аудиты → планы фиксов**.
|
|
186
|
-
Foundation (`docs/ux/foundation.md`) отвечает на «зачем», сценарии
|
|
187
|
-
(`docs/ux/scenarios.md`) — источник правды поведения, трассируются к
|
|
188
|
-
stories. Всё пишется и валидируется **до** интерфейса, обновляется тем же
|
|
189
|
-
изменением, что и поведение. Аудиты (`/ux-audit`) проверяют код против
|
|
190
|
-
сценариев вместе с acceptance criteria, вердикты PASS/PARTIAL/FAIL/BLOCKED
|
|
191
|
-
с доказательствами `file:line`; `/ux-audit coverage` ищет дыры в самой
|
|
192
|
-
цепочке. Установка: в
|
|
193
|
-
Claude Code — `/plugin marketplace add ssheleg/super-ux`, в Cursor —
|
|
194
|
-
`npx super-ux --cursor <проект>`. Дальше одна команда — `/ux`: сама ставит
|
|
195
|
-
правило и базу, а при повторных запусках показывает статус и следующий шаг.
|
|
229
|
+
Built by ssheleg — [sshlg.me](https://sshlg.me)
|
|
230
|
+
|
|
231
|
+
- X / Twitter — [@fuck_this_year](https://x.com/fuck_this_year)
|
|
232
|
+
- Telegram — [@sshlg](https://t.me/sshlg)
|
|
233
|
+
|
|
234
|
+
Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
|
|
235
|
+
`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
|
|
236
|
+
One command installs all five for every agent you use:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
npx sshlg-skills install
|
|
240
|
+
```
|
|
196
241
|
|
|
197
242
|
## License
|
|
198
243
|
|
package/bin/super-ux.js
CHANGED
|
@@ -74,7 +74,9 @@ function installCursor(target, force) {
|
|
|
74
74
|
}
|
|
75
75
|
}
|
|
76
76
|
|
|
77
|
-
|
|
77
|
+
for (const dir of ['audits', 'plans']) {
|
|
78
|
+
fs.mkdirSync(path.join(target, 'docs', 'ux', dir), { recursive: true });
|
|
79
|
+
}
|
|
78
80
|
for (const tpl of ['scenarios', 'foundation', 'flows', 'screens', 'README']) {
|
|
79
81
|
const dst = path.join(target, 'docs', 'ux', `${tpl}.md`);
|
|
80
82
|
if (fs.existsSync(dst)) {
|
|
@@ -85,9 +87,19 @@ function installCursor(target, force) {
|
|
|
85
87
|
}
|
|
86
88
|
}
|
|
87
89
|
// The linter is code, not a template — refresh it to the shipped version.
|
|
90
|
+
// Shipped via package.json files[]; if that ever regresses, warn instead of
|
|
91
|
+
// dying on an ENOENT stack trace after the rules are already installed.
|
|
92
|
+
const lintSrc = path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py');
|
|
88
93
|
const lintDst = path.join(target, 'docs', 'ux', 'lint.py');
|
|
89
|
-
fs.
|
|
90
|
-
|
|
94
|
+
if (fs.existsSync(lintSrc)) {
|
|
95
|
+
fs.copyFileSync(lintSrc, lintDst);
|
|
96
|
+
console.log(`sync: ${lintDst}`);
|
|
97
|
+
} else {
|
|
98
|
+
console.error(
|
|
99
|
+
`warning: linter not found in this package (${lintSrc}); docs/ux/lint.py was not installed.\n` +
|
|
100
|
+
` Get it from https://github.com/${REPO}/blob/main/plugins/super-ux/scripts/ux_lint.py`
|
|
101
|
+
);
|
|
102
|
+
}
|
|
91
103
|
|
|
92
104
|
console.log(`done: ${installed} installed, ${skipped} skipped`);
|
|
93
105
|
}
|
|
@@ -12,7 +12,8 @@ alwaysApply: true
|
|
|
12
12
|
and (Figma on) its frame link. A screen that changes in code changes here in
|
|
13
13
|
the SAME change.
|
|
14
14
|
- Run the linter after any UX change and before calling work done:
|
|
15
|
-
`python3 docs/ux/lint.py
|
|
15
|
+
`python3 docs/ux/lint.py`. It must pass — drift must not merge; wire it
|
|
16
|
+
into CI/pre-commit.
|
|
16
17
|
- Any change that touches user-facing behavior MUST update
|
|
17
18
|
`docs/ux/scenarios.md` in the same change (add/adjust scenarios, statuses,
|
|
18
19
|
coverage). New user-facing behavior with no scenario is a blocker, not a
|
|
@@ -22,10 +23,15 @@ alwaysApply: true
|
|
|
22
23
|
against the existing base (conflicts, overlaps, gaps), approved. An idea
|
|
23
24
|
serving no job is challenged, not silently accepted.
|
|
24
25
|
- Do NOT write interface code until the UX workflow is done first: the
|
|
25
|
-
foundation → flows → scenarios chain is designed and approved,
|
|
26
|
-
Figma is enabled (default) — the UI is mocked up in Figma with
|
|
27
|
-
screen linked to its frame. Building UI before this is the exact
|
|
28
|
-
super-ux exists to prevent.
|
|
26
|
+
foundation → flows → screens → scenarios chain is designed and approved,
|
|
27
|
+
and — when Figma is enabled (default) — the UI is mocked up in Figma with
|
|
28
|
+
every screen linked to its frame. Building UI before this is the exact
|
|
29
|
+
mistake super-ux exists to prevent.
|
|
30
|
+
- Visual identity is one locked style pack, recorded once in `screens.md` →
|
|
31
|
+
Design system and used by every frame and every built screen — picked with
|
|
32
|
+
the **sheleg-design** companion skill (`npx sheleg-design-skill`) when the
|
|
33
|
+
project has no design system of its own. Recommended, never forced; a
|
|
34
|
+
palette invented per screen is visual drift.
|
|
29
35
|
- Workflows: `ux-foundation` rule (WHY), `ux-flows` rule (flows + Figma
|
|
30
|
-
mockups), `ux-scenarios` rule (scenario base), `ux-audit` rule
|
|
36
|
+
mockups + style pack), `ux-scenarios` rule (scenario base), `ux-audit` rule
|
|
31
37
|
(evidence-backed audits).
|
|
@@ -15,8 +15,9 @@ verdict BLOCKED with the exact reason. Never guess, never a courtesy PASS.
|
|
|
15
15
|
|
|
16
16
|
## Loop
|
|
17
17
|
|
|
18
|
-
1. Read the base
|
|
19
|
-
|
|
18
|
+
1. Read the base (and foundation/flows/screens when they exist); scope =
|
|
19
|
+
all | feature:<name> | ID range | coverage; note the git SHA of `docs/ux`
|
|
20
|
+
for the report header; skip retired scenarios.
|
|
20
21
|
2. Batch by feature, ~5–8 scenarios per batch; list batches up front.
|
|
21
22
|
3. Per scenario check against the code: entry point reachable; every step
|
|
22
23
|
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.
|
|
|
26
27
|
`[AUD-YYYY-MM-DD-NN] (critical|major|minor) description -> suggested fix`.
|
|
27
28
|
4. Verdicts: PASS (complete), PARTIAL (flow exists, gaps), FAIL (missing or
|
|
28
29
|
broken), BLOCKED (cannot verify — say why).
|
|
30
|
+
When `flows.md`/`screens.md` exist, also check conformance: every flow
|
|
31
|
+
node reachable and every edge (error edges included) wired; every
|
|
32
|
+
registered screen's states rendered and its `Coverage` accurate — code
|
|
33
|
+
that diverges from a screen's record is a `drifted` finding. Scope
|
|
34
|
+
`coverage` audits the chain itself (orphan stories/flows/screens/
|
|
35
|
+
scenarios, journey stages without scenarios, personas unused).
|
|
29
36
|
5. Write the report batch by batch: header (scope, method, base SHA),
|
|
30
37
|
Summary (totals, top issues, prioritized next actions), per-batch
|
|
31
38
|
verdicts with evidence, findings-register table.
|
|
@@ -20,8 +20,14 @@ Fields: `Traces` (story/job IDs), `Goal` (observable end state), `Entry
|
|
|
20
20
|
points` (ALL of them), `Success exit`, `Task analysis` (numbered
|
|
21
21
|
user-visible micro-steps), mermaid `flowchart` (screens as
|
|
22
22
|
`Screen: <name>`, decisions as diamonds, `*_err` error nodes with labeled
|
|
23
|
-
recovery edges), `Screens
|
|
24
|
-
|
|
23
|
+
recovery edges), `Screens traversed` table (`| Screen | States used here |`
|
|
24
|
+
— SCR-IDs only; the full per-screen spec lives once in `screens.md`).
|
|
25
|
+
|
|
26
|
+
Each screen entry in `screens.md`: `Used by`, `Purpose`, `Elements` (mark
|
|
27
|
+
the ONE primary action), `States` table (`| State | Trigger | Figma frame |
|
|
28
|
+
Behavior |` — a row per loading/empty/error/success that applies),
|
|
29
|
+
`Wireframe`, `Coverage` (file:line), `Scenarios`, `Resources`, `Status`
|
|
30
|
+
(designed|built|drifted|retired).
|
|
25
31
|
|
|
26
32
|
## Design rules
|
|
27
33
|
|
|
@@ -33,9 +39,20 @@ loading/empty/error/success + key elements, one primary action).
|
|
|
33
39
|
- Wireframes optional (`docs/ux/wireframes/FLW-NN.md`, ASCII hierarchy +
|
|
34
40
|
primary action, not pixels); storyboard only when usage context drives
|
|
35
41
|
design.
|
|
42
|
+
- Visual identity BEFORE any frame: `screens.md` → Design system →
|
|
43
|
+
`Style pack`. Empty and no design system in the project → pick a pack with
|
|
44
|
+
the **sheleg-design** companion skill (`workbench` for product UI /
|
|
45
|
+
dashboards / tools, `instrument-console`, `editorial-luxury`, or a new
|
|
46
|
+
pack on its contract; cinematic scroll pages also take its motion
|
|
47
|
+
methodology) and record the pack + token file. Missing → offer the
|
|
48
|
+
one-time install once (`npx sheleg-design-skill`) and continue on platform
|
|
49
|
+
defaults; recommend, don't force. The pack owns palette/type/motion and
|
|
50
|
+
its bans; BP-079..090 stay the floors it must clear. Never invent a look
|
|
51
|
+
per screen.
|
|
36
52
|
- Figma mockups optional (default on): if the foundation's Design tooling
|
|
37
53
|
enables Figma and a Figma MCP is available, mirror each screen into a
|
|
38
|
-
frame
|
|
54
|
+
frame built on the pack's tokens (they become the Figma variable
|
|
55
|
+
collections) applying visual-craft practices (BP-079..090), and link every
|
|
39
56
|
screen row to its frame; ask the user once at the start of design.
|
|
40
57
|
- Backwards mode (existing product): reconstruct flows as they ARE from
|
|
41
58
|
code with file:line evidence, tag `inferred` until confirmed; gaps
|
|
@@ -42,6 +42,15 @@ deleted.
|
|
|
42
42
|
INVEST, observable criteria), coverage (persona→job→journey→story chain
|
|
43
43
|
complete; must/should stories have scenarios).
|
|
44
44
|
|
|
45
|
+
Two more sections this file owns, filled when they apply: **Monetization**
|
|
46
|
+
(model + value metric + free boundary + purchase surface + money moments +
|
|
47
|
+
acquisition coherence — each money moment becomes a first-class flow, and a
|
|
48
|
+
web/web2app purchase surface makes the web funnel and the paid handoff flows
|
|
49
|
+
of this product too) and **Design
|
|
50
|
+
tooling** (the Figma on/off choice, default on, plus the project's Figma file
|
|
51
|
+
URL — asked once per project). Everything else about the visual layer, the
|
|
52
|
+
design system and the style pack, lives in `docs/ux/screens.md`.
|
|
53
|
+
|
|
45
54
|
Evidence beats opinion: mark unvalidated guesses as assumptions
|
|
46
55
|
(desirability/viability/feasibility/usability) and test risky ones before
|
|
47
56
|
building on them.
|
|
@@ -21,8 +21,10 @@ JRN-01/#2)`), enforce traceability — every must/should story covered by ≥1
|
|
|
21
21
|
scenario, every scenario serves ≥1 story or job.
|
|
22
22
|
|
|
23
23
|
Scenario entry fields (exact names): `Persona`, `Feature`, `Traces`, `Entry point`,
|
|
24
|
-
`Preconditions`, `Steps` (numbered, one user action each
|
|
25
|
-
|
|
24
|
+
`Preconditions`, `Steps` (numbered, one user action each, paired with the
|
|
25
|
+
observable system response), `Expected result` (observable), `Alt paths`
|
|
26
|
+
(meaningful non-error deviations — skip/dismiss/alternate route — omit only
|
|
27
|
+
when none exist), `UI elements` (every button/field/link/dialog/toast involved —
|
|
26
28
|
this is what audits check), `States covered` (loading|empty|error|success),
|
|
27
29
|
`Errors & recovery` (each failure: what the user sees, how they recover),
|
|
28
30
|
`Status` (draft|validated|implemented|retired), `Coverage` (file:line or
|
|
@@ -35,7 +37,12 @@ never deleted. Lifecycle: draft → validated (human approval) → implemented
|
|
|
35
37
|
Per-feature completeness: happy path, every error path, empty state, visible
|
|
36
38
|
loading, destructive-action confirmation, returning-user variant.
|
|
37
39
|
Per-product: first-run onboarding, every core flow, settings, multi-entity
|
|
38
|
-
flows (e.g. second project), account/data lifecycle
|
|
40
|
+
flows (e.g. second project), account/data lifecycle, and — when the product
|
|
41
|
+
earns money — the monetization flows: paywall (first-session placement),
|
|
42
|
+
trial start/end, upgrade-at-limit, cancel + winback, rating prompt after
|
|
43
|
+
success moments, plus the web funnel (landing, pricing, signup, checkout,
|
|
44
|
+
abandonment, failed payment) and the paid handoff with its failure branches
|
|
45
|
+
when money is taken on the web.
|
|
39
46
|
|
|
40
47
|
## Workflows
|
|
41
48
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "super-ux",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Scenario-driven UI development for AI agents (Claude Code +
|
|
3
|
+
"version": "0.26.1",
|
|
4
|
+
"description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"super-ux": "bin/super-ux.js"
|
|
7
7
|
},
|
|
@@ -9,12 +9,16 @@
|
|
|
9
9
|
"bin",
|
|
10
10
|
"cursor",
|
|
11
11
|
"templates",
|
|
12
|
+
"plugins/super-ux/scripts/ux_lint.py",
|
|
12
13
|
"README.md",
|
|
13
14
|
"LICENSE",
|
|
14
15
|
"CHANGELOG.md"
|
|
15
16
|
],
|
|
16
17
|
"repository": "github:ssheleg/super-ux",
|
|
17
18
|
"homepage": "https://github.com/ssheleg/super-ux",
|
|
19
|
+
"bugs": {
|
|
20
|
+
"url": "https://github.com/ssheleg/super-ux/issues"
|
|
21
|
+
},
|
|
18
22
|
"license": "MIT",
|
|
19
23
|
"author": "ssheleg",
|
|
20
24
|
"engines": {
|